Contents
VBINI Function Reference
Version 1.10 - April 1997
Copyright (C) Karri Software Ltd. 1997.

Contents of VBINI Function Reference

To learn how to use Help, please press F1.

Introduction

Installing and Using

VBINI Function Reference

VBINI Error Codes

Ordering Information

Technical Support

Copyright and Warranty

Trademarks


 Introduction

VBINI.DLL is a Dynamic Link Library containing a set of internal routines for Visual Basic(*) which give you total control over Windows Initialisation (.INI) files.

The use of the Windows API for the same functionality can be cumbersome as well as restricted; for example you cannot delete INI entries because you cannot pass a NULL pointer to the Windows API from Visual Basic. Some third party VBXs are fine but again, quite cumbersome to use.

VBINI.DLL was designed to give you full access to INI files as well as being very easy to use. As the routines are internal, you may use them identically to any of the actual Visual Basic internal routines. In case of errors, for example, the runtime variable Err is set to the appropriate error, rather than having to check for a return code from an API.

The DLL also gives you functionality which does not exist even within the Windows API, namely INI file Section management.

With the functionality provided, you could easily write an INI file editor with VBINI.DLL.

(*) See Trademarks


 Installing and Using

Installation:

Copy VBINI.DLL to your Windows System directory or any other directory specified in your PATH statement.

Using:

Include the file VBINI.BAS in your project by using the File/Add File... command in the Visual Basic menu.

You can also run the sample applet which shows you how to use some of the routines.


Function Reference

 VBINI Function Reference

Section Management:
IniGetSectionCount	Returns the number of sections in an INI file
IniGetSections	Gets section names into a string array
IniDeleteSection	Deletes a section
IniRenameSection	Renames a section
IniClearSection	Clears all entries in a section

Entry Management:
IniGetEntryCount	Returns the number of entries in a section
IniGetEntries	Gets entry names into a string array
IniDeleteEntry	Deletes an entry
IniRenameEntry	Renames an entry
IniClearEntry	Clears an entry

Value Management:
IniGetStr	Gets a string value
IniSetStr	Sets a string value
IniGetInt	Gets an integer value
IniSetInt	Sets an integer value

Helper Routines:
IniFlushCache	Flushes the INI file to disk
IniGetSectionsCombobox	Inserts section names into a combobox
IniGetSectionsListbox	Inserts section names into a listbox
IniGetEntriesCombobox	Inserts entry names into a combobox
IniGetEntriesListbox	Inserts entry names into a listbox


 IniGetSectionCount
Returns the number of sections in an INI file

Declaration:

Declare Function IniGetSectionCount Lib "VBINI.DLL" (ByVal IniFile$) As Integer

Parameters:

IniFile$	Name of the INI file.

Return value:

Integer	The number of sections found in the INI file.

Errors:

VBI_ERR_FILE_NOT_FOUND

Example:
Dim n%

n = IniGetSectionCount("WIN.INI")
MsgBox Format$(n) & " sections found."


 IniGetSections
Gets section names into a string array

Declaration:

Declare Sub IniGetSections Lib "VBINI.DLL" (ByVal IniFile$, Array$())

Parameters:

IniFile$	Name of the INI file.
Array()$	Output string array for the section names.

Comments:

The parameter Array$() must be ReDimmed to the number of sections which are returned. You may use IniGetSectionCount to obtain this value.

Errors:

VBI_ERR_FILE_NOT_FOUND
VBI_ERR_NOT_ENOUGH_MEM

Example:
Dim IniFile$
Dim Sect$()
Dim n%
Dim i%

IniFile = "WIN.INI"
n = IniGetSectionCount(IniFile)
ReDim Sect(n) 'Allocate memory
IniGetSections IniFile, Sect()
For i = 1 to n
  MsgBox Sect(i)
Next


 IniDeleteSection
Deletes a section

Declaration:

Declare Sub IniDeleteSection Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$)

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section to be deleted.

Errors:

VBI_ERR_FILE_NOT_FOUND

Example:
'Deletes the section Desktop
IniDeleteSection "C:\TEMP\TEST.INI", "Desktop"


 IniRenameSection
Renames a section

Declaration:

Declare Sub IniRenameSection Lib "VBINI.DLL" (ByVal IniFile$, ByVal oldSection$, ByVal newSection$)

Parameters:

IniFile$	Name of the INI file.
oldSection$	Name of the section to be renamed.
newSection$	New name for the section to be renamed.

Errors:

VBI_ERR_FILE_NOT_FOUND
VBI_ERR_MISSING_SECTION_NAME

Example:
'Renames Desktop to MyDesktop
IniRenameSection "C:\TEMP\TEST.INI", "Desktop", "MyDesktop"


 IniClearSection
Clears all entries in a section

Declaration:

Declare Sub IniClearSection Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$)

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section to be cleared.

Errors:

VBI_ERR_FILE_NOT_FOUND
VBI_ERR_MISSING_SECTION_NAME

Example:
'Clears all entries in the section Desktop
IniClearSection "C:\TEMP\TEST.INI", "Desktop"


 IniGetEntryCount
Returns the number of entries in a section

Declaration:

Declare Function IniGetEntryCount Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$) As Integer

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section the entries are required for.

Return value:

Integer	The number of entries found in the section.

Example:
Dim n%

n = IniGetEntryCount("WIN.INI", "Desktop")
MsgBox Format$(n) & " entries found for Desktop."


 IniGetEntries
Gets entry names into a string array

Declaration:

Declare Sub IniGetEntries Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$, Array$())

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section for the entry names.
Array()$	Output string array for the entry names.

Comments:

The parameter Array$() must be ReDimmed to the number of entries which are returned. You may use IniGetEntryCount to obtain this value.

Errors:

VBI_ERR_NOT_ENOUGH_MEM

Example:
Dim IniFile$
Dim Ents$()
Dim n%
Dim i%

IniFile = "WIN.INI"
n = IniGetEntryCount(IniFile, "Desktop")
ReDim Ents(n) 'Allocate memory
IniGetEntries IniFile, "Desktop", Ents()
For i = 1 to n
  MsgBox Ents(i)
Next


 IniDeleteEntry
Deletes an entry

Declaration:

Declare Sub IniDeleteEntry Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$, ByVal Entry$)

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section under which the entry is to be deleted.
Entry$	Name of the entry to be deleted.

Errors:

VBI_ERR_INI_WRITE_FAIL

Example:
'Deletes the entry Pattern in the section Desktop
IniDeleteEntry "C:\TEMP\TEST.INI", "Desktop", "Pattern"


 IniRenameEntry
Renames an entry

Declaration:

Declare Sub IniRenameEntry Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$, ByVal oldEntry$, ByVal newEntry$)

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section under which the entry is to be renamed.
oldEntry$	Name of the entry to be renamed.
newEntry$	New name for the entry to be renamed.

Errors:

VBI_ERR_FILE_NOT_FOUND
VBI_ERR_MISSING_ENTRY_NAME
VBI_ERR_INI_WRITE_FAIL

Example:
'Renames Pattern to MyPattern under the section Desktop
IniRenameEntry "C:\TEMP\TEST.INI", "Desktop", "Pattern", "MyPattern"


 IniClearEntry
Clears an entry (sets it blank)

Declaration:

Declare Sub IniClearEntry Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$, ByVal Entry$)

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section under which the entry is to be cleared.
Entry$	Name of the entry to be cleared (set to blank, not deleted).

Errors:

VBI_ERR_INI_WRITE_FAIL

Example:
'Clears the entry Pattern in the section Desktop
IniClearEntry "C:\TEMP\TEST.INI", "Desktop", "Pattern"

TEST.INI would look like:
[Desktop]
Pattern=


 IniGetStr
Gets a string value

Declaration:

Declare Function IniGetStr Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$, ByVal Entry$, ByVal Default$) As String

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section under which the entry is to be found.
Entry$	Name of the entry for which the value is required.
Default$	If the entry is not found, return this value instead.

Return value:

String	The value found as a string or the default string.

Errors:

VBI_ERR_NOT_ENOUGH_MEM

Example:
'Display the value for Pattern in the section Desktop
MsgBox IniGetStr ("C:\TEMP\TEST.INI", "Desktop", "Pattern", "")


 IniSetStr
Sets a string value

Declaration:

Declare Sub IniSetStr Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$, ByVal Entry$, ByVal Value$)

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section under which the entry is to be found.
Entry$	Name of the entry for which the value is set.
Value$	Value to be set.

Errors:

VBI_ERR_INI_WRITE_FAIL

Example:
'Set the value for Pattern to be Striped in the section Desktop
IniSetStr "C:\TEMP\TEST.INI", "Desktop", "Pattern", "Striped"

TEST.INI would look like:
[Desktop]
Pattern=Striped


 IniGetInt
Gets an integer value

Declaration:

Declare Function IniGetInt Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$, ByVal Entry$, ByVal Default%) As Integer

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section under which the entry is to be found.
Entry$	Name of the entry for which the value is required.
Default%	If the entry is not found, return this value instead.

Return value:

Integer	The value found as an integer or the default value.

Example:
'Display the value for Pattern in the section Desktop
MsgBox Format$(IniGetInt ("C:\TEMP\TEST.INI", "Desktop", "Pattern", 0))


 IniSetInt
Sets an integer value

Declaration:

Declare Sub IniSetInt Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$, ByVal Entry$, ByVal Value%)

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section under which the entry is to be found.
Entry$	Name of the entry for which the value is set.
Value%	Value to be set.

Errors:

VBI_ERR_INI_WRITE_FAIL

Example:
'Set the value for Pattern to be 7 in the section Desktop
IniSetInt "C:\TEMP\TEST.INI", "Desktop", "Pattern", 7

TEST.INI would look like:
[Desktop]
Pattern=7


 IniFlushCache
Make Windows flush the cache.

Declaration:

Declare Sub IniFlushCache Lib "VBINI.DLL" (ByVal IniFile$)

Parameters:

IniFile$	Name of the INI file.

Comments:

To improve performance, Windows keeps a cached version of the most-recently accessed initialization file. Use this routine to make Windows flush the cache.

Errors:

VBI_ERR_CACHE_FAIL

Example:
'Flush the cache
IniFlushCache "C:\TEMP\TEST.INI"


 IniGetSectionsCombobox
Inserts section names into a combobox

Declaration:

Declare Sub IniGetSectionsCombobox Lib "VBINI.DLL" (ByVal IniFile$, ByVal hwndCombo%)

Parameters:

IniFile$	Name of the INI file.
hwndCombo%	Window handle of the combobox.

Errors:

VBI_ERR_FILE_NOT_FOUND

Example:
'Dump all sections in WIN.INI to a combo
IniGetSectionsCombobox "WIN.INI", Combo1.hWnd


 IniGetSectionsListbox
Inserts section names into a listbox

Declaration:

Declare Sub IniGetSectionsListbox Lib "VBINI.DLL" (ByVal IniFile$, ByVal hwndList%)

Parameters:

IniFile$	Name of the INI file.
hwndList%	Window handle of the listbox.

Errors:

VBI_ERR_FILE_NOT_FOUND

Example:
'Dump all sections in WIN.INI to a listbox
IniGetSectionsListbox "WIN.INI", List1.hWnd


 IniGetEntriesCombobox
Inserts entry names in a section into a combobox

Declaration:

Declare Sub IniGetEntriesCombobox Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$, ByVal hwndCombo%)

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section whose entries are inserted.
hwndCombo%	Window handle of the combobox.

Errors:

VBI_ERR_FILE_NOT_FOUND

Example:
'Dump all entries in the section Desktop of WIN.INI to a combo
IniGetEntriesCombobox "WIN.INI", "Desktop", Combo1.hWnd


 IniGetEntriesListbox
Inserts entry names in a section into a listbox

Declaration:

Declare Sub IniGetEntriesListbox Lib "VBINI.DLL" (ByVal IniFile$, ByVal Section$, ByVal hwndList%)

Parameters:

IniFile$	Name of the INI file.
Section$	Name of the section whose entries are inserted.
hwndList%	Window handle of the listbox.

Errors:

VBI_ERR_FILE_NOT_FOUND

Example:
'Dump all entries in the section Desktop of WIN.INI to a listbox
IniGetEntriesListbox "WIN.INI", "Desktop", List1.hWnd


 Error Codes

Upon errors, VBINI.DLL sets the Visual Basic internal variable Err to the following values:

VBI_ERR_FILE_NOT_FOUND	INI file not found
VBI_ERR_NOT_ENOUGH_MEM	Memory allocation failure
VBI_ERR_INI_WRITE_FAIL	A write to the INI file failed
VBI_ERR_CACHE_FAIL	Flushing the cache failed
VBI_ERR_MISSING_SECTION_NAME	A section was not specified
VBI_ERR_MISSING_ENTRY_NAME	An entry name was not specified


 Ordering Information

Price:

15 US Dollars

To have your registration added to your CompuServe bill, please GO SWREG and follow the instructions.

Please use the registration ID 12769.

We will send you the registered version (without the intro message box) via Email upon receiving notification from CompuServe.


 Technical Support

In case of problems with the routines or if you have any questions about the product, please contact us via email on 100422,3521. We will answer any queries or fix any bugs that you might have.


Disclaimer

 Copyright and Warranty

VBINI 1.10
Copyright (C) Karri Software Limited 1997

Disclaimer of Warranty

THIS SOFTWARE AND THE ACCOMPANYING FILES ARE SOLD "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

THE USER MUST ASSUME THE FULL RISK OF USING THIS SOFTWARE.

ANY LIABILITY OF THE SELLER WILL BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF THE PURCHASE PRICE WITHIN 90 DAYS OF RECEIPT.


Trademarks

Windows is a registered trademark of Microsoft Corporation.
Windows 3.1, Windows for Workgroups 3.11, Windows 95 and Windows NT are registered trademarks of Microsoft Corporation.
Visual Basic is a trademark of Microsoft Corporation.